nice_things/log/log.sh

This module provides log functions. There are six levels of logs, from lowest to highest: 0 | none, 1 | error, 2 | warn, 3 | info, 4 | debug, 5 | trace. When a log level is chosen, all lower levels up to that level are active. Level 3 | info is the default.

The run time log level is configured using an environment variable, which defaults to LOG_LEVEL, but can be changed in nice_package.conf. A log level can be chosen either by name or by number. Besides the log level, color or no-color can be set, after a comma. The output is colored by default, and that can also be changed in nice_package.conf.

Because the configuration applies to the whole module, it is documented here instead of in each function bellow:

[module:nice_things/log/log.sh]
# If true, info logs will be preceded by their level name (INFO), like the other levels
named_info=false
# If true, runtime config will default to 'no-color'
no_color=false
# Name of the variable used for runtime configuration
variable=LOG_LEVEL

initialize_log

Since 0.3.0 · Source

import "{ initialize_log }" from nice_things/log/log.sh

Synopsis
initialize_log [<level>] [<color>]

Configuration
–

Description
Initialize log functions. Logs are initialized on import, you don't need to call this function unless you want to change logging configuration, e.g., if you accept "quiet" or "verbose" command-line options.

Logs can be initialized many times, with optional changes of <level> and/or <color> settings. If a parameter is null or omitted, the value of the LOG_LEVEL environment variable is used if set, otherwise defaults from nice_package.conf are used.

Options
–

Operands

• <level>: A log level as number between 0-5, or by name. Optional, or can be set to the null string to ignore.
• <color>: Optional, may be set to color or no-color.

Stdin
–

Stdout
–

Stderr
–

Exit status
0: Successful completion.

Abort
–

Usage examples

initialize_log info color

log_debug

Since 0.3.0 · Source

import "{ log_debug }" from nice_things/log/log.sh

Synopsis
log_debug <message>…

Configuration
–

Description
Print debug log to stderr.

Options
–

Operands
<message>: Log message.

Stdin
–

Stdout
–

Stderr
Log message output.

Exit status
0: Successful completion.

Abort
–

Usage examples

log_debug "Got arguments: $(to_string "$@")"

log_error

Since 0.3.0 · Source

import "{ log_error }" from nice_things/log/log.sh

Synopsis
log_error <message>…

Configuration
–

Description
Print error log to stderr.

Options
–

Operands
<message>: Log message.

Stdin
–

Stdout
–

Stderr
Log message output.

Exit status
0: Successful completion.

Abort
–

Usage examples

log_error "Something went wrong"

log_info

Since 0.3.0 · Source

import "{ log_info }" from nice_things/log/log.sh

Synopsis
log_info <message>…

Configuration
–

Description
Print info log to stderr.

Options
–

Operands
<message>: Log message.

Stdin
–

Stdout
–

Stderr
Log message output.

Exit status
0: Successful completion.

Abort
–

Usage examples

log_info "Some information about the process"

log_is_level

Since 0.3.0 · Source

import "{ log_is_level }" from nice_things/log/log.sh

Synopsis
log_is_level <level>

Configuration
–

Description
Check if logs up to the specified <level> are active. <level> can be either the name or number of a log level. Accepted levels are 1 | error, 2 | warn, 3 | info, 4 | debug, 5 | trace.

Options
–

Operands
<level>: A log level.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Log <level> is active.
• 1: Log <level> is not active.

Abort
–

Usage examples

# log_is_level can be use to avoid expanding expensive expressions when a log won't be printed
if log_is_level trace; then
	log_trace "Got arguments: $(to_string "$@")"
fi

log_trace

Since 0.3.0 · Source

import "{ log_trace }" from nice_things/log/log.sh

Synopsis
log_trace <message>…

Configuration
–

Description
Print trace log to stderr.

Options
–

Operands
<message>: Log message.

Stdin
–

Stdout
–

Stderr
Log message output.

Exit status
0: Successful completion.

Abort
–

Usage examples

log_trace "Got arguments: $(to_string "$@")"

log_warn

Since 0.3.0 · Source

import "{ log_warn }" from nice_things/log/log.sh

Synopsis
log_warn <message>…

Configuration
–

Description
Print warning log to stderr.

Options
–

Operands
<message>: Log message.

Stdin
–

Stdout
–

Stderr
Log message output.

Exit status
0: Successful completion.

Abort
–

Usage examples

log_warn "Something non-critical went wrong"